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1.0 IMEQPUCIIflM 
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1.1 £Ufi£IU£ 

This document describes the conventions end procedures to be used 
by programmers in the development and Maintenance of Distributed 
Communications Network Software CDCNS1 in the CYBIL 
Implementation language* 

There are a variety of routine* aundane aspects associated with 
writing programs, a set of coding conventions reaove froa the 
prograaaer trivial decisions relating to aodule foraat* naae 
generation* etc. thereby leaving more tlae to concentrate on the 
important matters* 

During the lifetime of a targe software product* the average- 
developer will come In contact with a large number of programs 
written by and maintained by many other programmers* A -v 
consistent set of coding conventions helps the programmer "feel 
at home" with a new program and therefore Is able to begin doing- ' 
useful work sooner* 

The Implementation of these conventions will increase the 
efficiency of program development* improve the reliability and 
maintainability of the prograa and aid In the training of persons 
who will be aaintaining or using the prograa* 



1.2 BE£EBEttCE-M£UB£ttIs 

Prograaaers using this convention should also be faailiar with 
the CY BH l« o lamen tation -Deo efldent-Hsudbjmk (DCS fARH3078). This 
convention used the "CYBIL Program Library Conventions" and the 
"CYBIL Coding Conventions" sections froa the CY8IL Handbook •% 
guidelines* The following sections froa the Handbook are also of 
particular Interest* 

• "CYBIL-CH/IH Type and Variable Happing" - describes the 
MC68000 data foraats for each of the supported CYBIL data types* 

• "CYBIL-CH/IH Run Time Environment" - describes the run time 
environmentt memory* parameter passing* variables* heap 

management* etc. f ~\ 
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. "Procedure Intorftct Conventions" - describes conventions thst 
should generelfy be used by designers of procedural interfaces* 
The conventions in this section should be followed by programmers 
using the ACSO Coding Convention* 

• "Efficiencies (General and CHI" — lists a group of programming 
tips to help the user better utilize the CYBIL development 
environment. It Mill be added to as additional tips become 
known* 

• "Implementation Limitations (General and CH)" - describes 
Implementation limitations* 

The FRS for the CYBIL-EnraeiieX-JLl^Q IOCS #ARH261<Jt is enother 
document that programmers using this convention should be 
familiar with. This document describes CYBFORH. the utility used 
to format CYBIL source code to maximize readability* 

CYBFORH Is the major software tool for enforcing ACSO coding 
conventions* All programs MUST be run through the formatter. If 
additional code is added after this process* It is required to be 
in the seme format or the program must be run through CYBFORH 
again* The formatter should be responsible for* 

- ell Indentation 

- capitalizing keywords 

- inserting the proper number of blank lines 

- jjip^ortTWg ^^c^e-r-ac^tjULJLflSUiCA-J^fte-s^ — —■—-- 

- repeating the label at the end of e structured block 

- etc* 



i*3 cjui£amac£-Aaa-EiLEQM£fliai 

The spirit of the conventions as well es the specifics should be 
adhered to* The enforcement of these conventions and the 
acceptance of "reasonable deviations" are the responsibility of 
the code reviewers* Programs which do not conform to these 
conventions will be returned to the programmer for correction* 

If parts of the convention ere found to be unworkable or If some 
Issues are found not to be covered* this document should be 
updated* 
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2.0 QQ£Ufl£!iIlIIflll 



2.1 EUBEQSE 

The prlaary purpose of doeuaentstion is to help soaeone other 
then the original developer understand what the code is doing* 

2.2 £EUE&AL-B£flUia£UEHIS 

Coaaents within CYBIL code should provide njulLiJllUUUal 
inforaatlon describing why or what a series of CYBIl stateaents 
are doing. 

All docuaentatlon and coaaent lines should contain complete 
English sentences with correct punctuation* Exceptions are 
« Mowed in eabedded coaaents* titles and data declaration stand' 
alone coaaents (such as "Work codes for Intertask aessages.**). /-*- 

Oocuaentation should avoid the use of personal pronouns (he* she* 
hie* her* etc*)* 

When feasible* coaaents should be kept general enough so that 
they Mill not becoae outdated by detailed chenges to the code* 
Where values are defined by constants (CONST)* the naae rather 
than the value should be referenced in the docuaentatlon* 

The abbreviations for technical teras which ere to be used In 
docuaentatlon are listed In Appendix A* A aodule whose 
docuaentatlon aakes extensive use of teras not In this list aay 
define a list of abbreviations and include It in the aodule level 
docuaentatlon* All other technleel words and phrases aust be 
coaptetely spelled out* Routine naaes and aneaonie naaes of 
tables and hardware coaponents are not considered abbreviations* 

2.3 PfipAqfiUE PQCUBEMHIIflM 

The Inforaation contained In e prologue should be at the level 
Indicated by the complexity of the code which It Is documenting* 

Defined formats exist for the inforaatlon provided in prologue 
docuaentatlon* The general foraat Is as follows* ,f- 
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- An uppercase keyword appears In column 3 followed by a "«»• 

- Text begins on the next line Indented two *P«es from the 
keyword* ond Hey contlnua Ut the sane level of Indentation! for 
as many lines as necessary* 

- Blank comment lines moy be used to separate paragraphs, but the 
indentation level should be maintained. 

- Where lists of variables/ parameters* acronym* or abbreviations 
and a description of each are used* the description continuation 
lines (If necessary) are indented 6 columns fro* the keyword. 

- Each keyword end the essocleted text must be separated from the 
next keyword by a blank comment line. 

The keywords that apply to each of the prologue documentation 
types are defined in the following sections. 

2.3.1 NODULE PROLOGUES 

{ PURPOSE* 

t A short description of what the module does. This should 

t conteln the purpose of the module and the reasons for 

C grouping the declarations In the module* rather then 

C describing the purpose of each procedure. 

I 

t A one or two paragraph overview description of the design 

C of the module. This should describe how the module works 

C In generel terms. Usage of specific variable or procedure 

C nemes Is discouraged. 
C 

{ A list of acronyms and abbreviations used In this module 

C (which are not defined In the appendix to this convention! 

C and their meaning. This section may be omitted If no new 

C acronyms or abbreviations are used in this module. 

C Copyright Control Data Corporation* 1984. 
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2.3.2 PRQGRAH/PROCEOURE/FUNCTION PROLOGUES 

For prograas* procedures end functions* the first line of the 
prologue block oust contsln the routine type followed by the 
routine naaet 

C PROGRAM prograa.naee or 

C PROCEOURE procedure.neee or 

C FUNCTION funetlon.naae 

This line is followed by e blenh eoaaent line end then the list 
of keywords end the associated text appropriate for the routine. 
The keywords which eey be used ere listed below. Any Keywords 
which ere not applicable ere to be oaltted. The keywords which 
ere used should appear In the order in which they are described 
below. 

- PURPOSE 

- DESCRIPTION r \ 

- CALL FORMAT W$ 

- COMMAND FORMAT 

- ENTRY CONDITIONS 

- EXIT CONDITIONS 

- ERROR CONDITIONS 

- INTERTASK MESSAGE INPUT 

- INTERTASK MESSAGE OUTPUT 

- GL08AL DATA REFERENCED 

- GLOBAL DATA MOOIFIED 

- NOTES AND CAUTIONS 

This foreet Is used for XREF/XDCL procedure end function heeder 
coaeon decks* for inline procedure coaaon decks* end for 
procedures and functions within a aodule. 

2.3.2.1 P.UBP0SE 

This section contains a short description of the process the 
procedure or function perfores trether then the aethod used). 
This section Is required. 

Exaapfet 

C PURPOSES 

C Perfora e physical copy of a aessege to a new buffer chain. 
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2.3.2.2 DESCRIPTION 



2.3.2.2 BESCBIEIIOM 

This section contains a one or two paragraph description of ^hou 

the procedure works* Normally this section should be Included, 

although for some short routines the PURPOSE section nay be 
sufficient* 

Example* 

DESCRIPTION* _ Mm . .. .. 

A nessage Is physically copied to new buffers* and the old 
set of buffers Is released. Data Is conpact In the new 
buffersi the first fn-11 buffers are full, and the last one 
has all of its enpty spece In the trolling portion of the 
buffer* 



2.3.2.3 Call EQBBAI 






This section is required for common Inline and 
routines. A line showing the calling fornat 

of eaeh of the parameters should be Included. 



callable 

a description 



externally 
followed by 



Examples 



C 

c 
c 
c 
c 

<. 
t 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 



CALL FORMAT* 

CIP*6ET SET.COUNT f PARANETER.NAHE. PVT. VAIUE.SET.COUNT, 
STATUS I 

PARAHETER.NAHE* (Inputl This parameter specifies the nana 
of the parameter for which the value set count »s to 
be returned. Any one of the names for the parameter 
nay be specified. 

PVT* Clnput) This parameter specifies the Parameter Value 
Table for the parameter list. 

VALUE SET COUNT* (output! The number of value sets given 
"for'the specified parameter Is returned In this 
parameter. 

STATUS* (output) The status of the request Is returned In 
this parameter. 
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2.3.2.* COMMANO FORMAT 

2.3.2.4 CQHWIMD.Ea&aU 

This section Is required for coaaand processors* It is used, to 
describe the coaaand Crether than the CALL FORMAT section used to 
describe the procedure interface). The first line of text should 
contain the singular for* of the coaaand naae* plural for* or 
alternate spelling of the coaaand naaa (if any}* and the 
abbreviation In the following foraat* 

C COMMANO NAME or PLURAL COMMANO NAME (ABBREVIATION) 

Following this line* each of the paraaeters should be described. 
The peraaetar naaa and alternate foras of the naae should be 
specified followed by the allowable values for the paraaeter and 
a description of the paraaeter. The description should include 
the default value for the paraaeter (if any). 

Exaaplet 

C COMMANO FORMAT! 
C SET.TIME (SETT) 

t HOUR (HOURS or H)> 0..23 This paraaeter specifies the 
C hour to set in the systea clock. 

C 

< MINUTE (MINUTES or MX 0..59 This paraaeter specifies 

t the alnutes to set in the systea clock. 

C 

C SECONO (SECONDS or S)« 0..59 This paraaeter specifies 

C the seconds to set in the systea clock. 

2.3.2.5 EMiax-Sflttttmotis 

This section describes any conditions which aust be aet before 
the routine Is called. Inforaatlon concerning peraaeters aay be 
specified If the coaaents on the prograa/procedure/function 
declaration are not sufficient. Entry conditions also include 
such things as the logical status of connections* files* buffers* 
etc* 

Exaaples 

C ENTRY CONOITIONSi 

C The user.fcb record aust be initialized via an open.file 

C request to the flle.access procedure. 
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2.0 DOCUMENTATION 
2.3.2.6 EXIT CONDITIONS 
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This section describes eny conditions which exist on • normal 
return fro* the routine* which the cslter should be autre of* A 
description of the return variable for functions (and procedures) 
■ay be specified If the comment on the function (or procedure) 
declaration Is not sufficient* Exit conditions elso inelude such 
things as the logical status of connections* files* buffers* etc* 

Examples 

€ EXIT CONDITIONS* 

C If the specified key is found in the tree* the associated 
{ data entry Is returned* otherwise the procedure return value 
{ will be NIL* 

2.3.2.7 EEEflE-CflaailUlMS 

This section describes any error conditions which exist on a 
return fro* the routine* which the caller should be aware of* 
Special processing done or parameter values returned are 
described* Error conditions way also Include such things as the 
logical status of connections* files* buffers* etc* 

Example* 

C ERROR CONDITIONS* 

{ The value of parameters line_number and command will be 

C undefined if an access error oeeurs when reeding the file* 

2.3.2.8 IttlEBIASK^ieSSafiE-iami 

This section contains a list of Intertask Messages received by 
this procedure* The intertask message workeode should be listed* 
followed by e description of the message* 

Examples 

C INTERTASK MESSAGE INPUT* 

C exec.tskfel II - This Intertask messsge Indicates thet e task 

< has failed due to a bus error or an address error* 

C se.start.task.for.user - This Intertesk message requests that 

{ a task be started for a user task such that System 

C Ancestor Is the parent. 



o 



2-7 

ACSD Coding Conventions 

April 20* 1964 



2.0 DOCUMENTATION 

2.3.2.9 INTERTASK MESSAGE OUTPUT 
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2.3.2.9 IMI£BIISKJl£SSA&£.QUI£m 

This section contains • list of intertask Messages sent by this 
procedure. The intertask Message Norkcode should be listed* 
followed by a description of the Message. 

Exaeple* 

< INTERTASK NESSA6E OUTPUTS 

< Hci.regutation.change - This intertask Message Is used to tell 
C " the SSR that a new regulation level is now to be put into 
C effect. 

2.3.2.10 filflEAiJUIA-&EEEaEM£Efl 
This section contains a list of the global date referenced. 

ExaMples 

< GLOBAL DATA REFERENCED* 
€ sys.cnfg.running 
C sys.enfg.blncloek 

2.3.2.11 fiLOBaL-DAIAJttflai£l£Q 

This section contains a list of the global data Modified and a 
description of the Modification. 

Example* 

C GLOBAL OATA HOOIFXEOt 

C coMMand.source - the address of the user that issued the 

C coMMend is saved. 

2.3.2.12 aQi£S_Aaa-£4micms 

This section documents design* iMpleMentatlon and general 
inforeatlon which May be useful to other analysts* especially any 
uneoMMon* unusual* or obscure techniques used by the coder. Also 
include warnings about problems that Might be encountered during 
Modification of this routine. 



,-r' 
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2.0 DOCUMENTATION 

2.3.2.12 NOTES AND CAUTIONS 






Examples 

NOTES ANO CAUTIONS* 

This is ■ highly tint consuming operation* requiring at 
least 3-5 microseconds per byte copied. It Is recommended 
that the caller either run at a relatively Iom task 
priority* or yield control sometime after the routine 
returns to avoid time slice overrun* and to permit other 
processes to be active* 



vy 
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Prologues for groups of declarations contain the keyword 
"DESCRIPTION" • The keyword is followed by one or more 
paragraphs describing what the relationship between the 
declarations Is (what they are for* how they are used and/or why 
they are grouped together). 

This format Is used for constant and type .declaration common 
decks* header decks for XREF variable declaration common decks* 
and may also precede blocks of related module level declarations. 
Coemon decks always contain a one line description and a blank 
comment line* which precedes the prologue. For examples 



CMDTTRE - Tree Management Definitions. 
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2.3.3 DECLARATION <CONST# TYPE AND VAR) PROLOGUES 
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The prologue for declarations within a Module should contain a 
slat tar short description line before the DESCRIPTION keyword and 
text. The declarations aay be preceded by e page eject end e 
title. For exaaptet 

T? NEVTXTLE !■ 'Directory H-E Data Stores** EJECT tt 

{ Olrectory N-E Data Stores* 

C 

C DESCRIPTIONS 

{ The following declarations define the data stores aalntalned 

{ by the Directory H-E. These are the Registered Oeta Store 

C CRDSI* the Translation Data Store CTDS1* end the Translation 

C Request Oete Store (TRDS1. 

C 

C The ROS contains ail the currently registered titles. 

{ These titles were created by a prlaitive. 

C 

C The TDS contains a list of the aost recent translations 

C received froa other systeas. The least recently used entry 

C is deleted. A threshold nuaber of entries are held In this 

C systea. 

C 

C The TRDS contains all the currently active translation V>? 

{ requests. 

2.% CODE LEVEL. QQCUfliMlAlIQH 

Source code is the ultiaate documentation of any prograa. 
Therefore* in all ACSD prograaalng. a consistent emphasis should 
be placed on producing lucid* readable end self-docuaent Ing code. 

Coaaents in the source code should only provide inforaetion not 
readily apparent froa reeding the code. If descriptive 
procedure* peraaeter and variable neaes are used* the nuaber of 
Inline coaaents should be minimal. 

In addition to prologue documentation* there are two types of 
code level coaaents* eabedded end stand alone coaaents. 

Embedded coaaents appear on the saae line following a declaration 
or executable statement. The comment need not be a complete 
sentence. This type of comment should not be continued onto 
another line. If the intended coaaent Is too long to fit on the 
single line* It should be inserted as a stand alone coaaent 
preceding the area of code to which it applies. Embedded 
comments should be used to convey software or systea attributes 
which are not dlscernabte froa CYBIL declarations. 
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' 2.« COOE LEVEL 00 



DOCUMENTATION 



Stind alont eoaeents art blocks of text appearing inline tilth 
code* as opposed to within the prologue blocks previously 
defined. All stand alone consents are preceded and followed by 
one blank line. The eoeaents are complete English sentences with 
correct punctuation. 
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3.0 tLAflIMfi_CQNJ£anQflS 

3.1 ££U££1L 

The key to Making prograas readable Is the usage of Meaningful, 
noncryptie English naaes for alt CYBIL constructs. Avoid the use 
of special characters ("$•* *3", and •*#**} in local naaes since 
these characters ear have- special aeanlng for global systea 

naming conventions. 

Naaes should be chosen for ho* they Mill read in the code body of 
a routine, not how they look In the data declaration. This is 
especially true or variables and field naaes in TYPE 
declarations. 

For exaaplet 

TYPE 

prograa.descr iptor • record x 

load.aapt load.aap.options,- ■ \ 

reeend, v -s 

load.aap.optlons ■ record 

flte.naeet flle.naae, 

options) (al I, nothing), 
recendf 

VAR 

ay.prograat prograa.descr! Ptorj 



ay.prograa.load.aap.fi le.naae »» «L0A0MAP»| 

Procedure and functions naaes should describe the process the 
procedure perforas. 

CYBIL stateaent labels are often needed In order to perform EXIT 
or CYCLE coaaands. Soaetlaes* structurally unnecessary labels 
can be powerful docuaentary aids and their use is encouraged. 
Label naaes should always describe the function being perforaed 
by the structured stateaent to which they refer. 
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For exaeplet 

/sooreh.synbol. table/ (Instead of) 

/labell/ 
Boolean naaes should always describe the TRUE condition* 
For exaeplet 

IF flle.is.open THEN (instead of) 

IF flle.SMitch THEN 
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Deck naaes have tha fot lowing foraat* 

ggtxxxx - where 

gg * two character group naae* 
t ■ one character Indicating deck type* 
xxxx * one to four character naae/aneaonle for uniqueness 
within the group* 

Allowable codes for the deck type are as follows* 



A 

B 
C 

- 
F 
H 
I 
I 
N 
T 

- X 
7 
B 

Deck 
unit 



MC68000 Assembler code 

Binder directives (coaaon deckl 

Coaaon deck calls feoaaon deck) 

CYBIL Constant and type declarations (coaaon deck) 

Installation procedure directives (coaaon deck) 

Docuaentation header (coaaon deck) 

CYBIL inline procedure (coaaon deck) 

Linker Directives (coaaon deck) 

CYBIL code aodule 

Type identifiers (coaaon deck) 

CYBIL XREF declaration (coaaon deck) 

Cyber 170 test stubs 

Cyber 180 test stubs 

of type N aust consist of exactly one aodule (coapllatlon 



A 



) 



Each group has a history 
naae). This deck contains 
which were added to the PL* 



deck naaed gg (where "gg" is the group 
a history of all decks In the group 
deleted froa the PL or aodlfied* 
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4.0 £M£-UI£UI 

The following sections define the code layout for modules* 
programs* procedures* functions and common decks* 

In general* declarations should be listed alphabetically within 
each declaration grouping (CONST* TYPE and VAR). Where a logical 
order is more meaningful* then that grouping may be used and a 
comment should describe what the logical grouping is. 

A logical order would be appropriate for related declarations 
such as the type and variable declarations for a table* or a 
major type and it's subordinate types. 

4.1 LAIUUI_£I2tlI2fiL 

4.1.1 PAGE EJECTS 

Page ejects inserted in appropriate places can make source 
listings more readable. All programs* procedures* functions and 
other large Items should be preceded with EJECT culls. 

4.1.2 TITLES 

Titles are required for each module* program* procedure* function 
and common deck. In addition* their use throughout the module is 
recommended to indicate such things as global variables and 
functional groupings of procedures. 

For example* the following title directives may be some of those 
used for a modules 

?? TITLE :« 'COCNET: Directory Management Entity 1 ?? 

?? NEWTITLE :« 'Directory M-E Data Stores 1 * EJECT ?? 
?? OLDTITLE ?? 

?? NEWTITLE :* 'PROGRAM dir_inlt»» EJECT ?? 
?? OLDTITLE ?? 

?? NFWTITLE ** 'Directory Registration Procedures' ?? 

?? NEWTITLE :» 'PROCEDURE t#GATE*XOCL] dir_change'» EJECT ?? 

?? 0L0TITLE ?? 
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?? NEWTITLE »• 'PROCEDURE C«GATE>XDCL1 dir_create»> EJECT ?? 

?? OLDTITLE ?? 

?? NEWTITLE :- 'PROCEOURE t#GATE»XDCLJ dir_delete»» EJECT ?? . 

?? OLDTITLE ?? 

?? NEWTITLE :« 'PROCEDURE [INLINE1 d Ir.reb.inl t« » EJECT ?? 

?? OLDTITLE ?? 
?? OLDTITLE ?? 

?? NEWTITLE s» 'Directory Translation Procedures* ?? 

?? NEWTITLE J» 'PROCEOURE C#GATE»XDCLJ d|r_abort«> EJECT ?? 

?? OLDTITLE ?? 

?? NEWTITLE s» "PROCEDURE [INLINE3 d i r.tcb.in I t • » EJECT ?? 

?? OLDTITLE ?? 

?? NEWTITLE :• 'PROCEDURE C#GATE»X0CL1 dl r.tr ans late* » EJECT ?T 

?? OLDTITLE ?? 
?? OLDTITLE ?? 

Note that the use of NEWTITLE and OLDTITLE allows "stacked" 
I isting titles to exist. • 



4.1.3 LISTING DIRECTIVES 



The LISTEXT listing toggle must be used to control the listing of 
common decKs. The calling deck may use the "?? PUSH ILISTEXT :» 
ON) ?? / ?? POP ??" directives around some or all common decks 
to alio* the listing to be controlled by the "LO 1 * list option on 
the CYBIL compiler command. The Nodule* Procedure and Common 
deck layout sections describe the directives to use and where 
they are to be located in the decks. 



v_y 
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» 



The code layout for a module is as follows* 

ggMxxxx 

*ifcall*BUILO»ggTxxxx 

?? TITLE :» »C0CNET« module purpose* ?? 

MODULE <module.name>} 

C Module prologue 

C . 

C . 

< . 

C (continue module prologue) 

?? LEFT :» 1* RIGHT :» 95 ?? 

?? FMT (FORMAT :- ON* KEYW :« UPPER* IDENT »• LOWER) ?? 

?? PUSH (LISTEXT :» ON) ?? 
<global *ealls of common decks> 
?? POP ?? 

<giobal TYPE* CONST and VAP decl ar at lons> 

<orogr am/procedur e/funct I on decl arations> 

MODENO <module.name>? 

The LISTEXT toggle is generally used to control listing of called 
common decks* however* common decks of major Importance to the 
module may always be listed* For example! 

<global ♦calls of common decks of major importance> 

?? PUSH (LISTEXT :» ON) ?? 

<global *calls of rest of common decks> 

?? POP ?? 

4.3 ££DSR^I!I££DCEaU»£ZEUIiaiICIl-UIQUI 

All CYBIL routines (including nested procedures) should begin on 
a new listing page and start with a prologue* A NEWTITLE line 
(which includes the page eject) precedes the prologue and 
specifies the type of routine ("PROGRAM". "PPCCEOURE" or 
•• FUNCTION")* attributes (if any) and the routine name. 

(4T\ An 3L0TITLE follows the PROCEND or FUNCENO statement. 



'O 
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In declarations of parameter Msts» always separate formal 
parameters by coding each parameter on a separate line. The 
program/procedure/function declaration may include comments 
following each parameter stating whether it is input (I)# output 
(0)» or both (I/O), followed by a description of the parameter. 

Always declare all input parameters before all output parameters 
unless there is an obvious symmetry that would be disturbed* 

The routine layout is as follows* 

?? NEWTITLE *■ •PROCEDURE Cattributesl proc.name 1 * EJECT ?? 

f. Procedure prologue 

{ . 

c . 



PROCEDURE proc.name ( t 

par_ls type; C It description of parameter 1 
VAR parl2» type; C I/C« description of parameter 2 






VAR par.nx type); i Os description of last parameter 



( optional ) 
( optional ) 
<TYPF, CONST and VAR decl arat!ons> 



?? PUSH (LISTEXT :» ON) ?? 
<*ca||s of common decks> 
?? POP ?? 



<nested procedure/ function decl aratl ons> 
?? SKIP :» 4 ?? or ?? EJECT ?? 
<body of the code> 



PRCCENO proc.name; 
?? OLOTITLE ?? 

For programs* the word PROGRAM is substituted for PPOCEOURE and 
for functions, the *ords FUNCTION and FUNCEND are substituted for 
PROCEDURE and PPQCEND respectively. 

For procedures which have a return value and for functions* the 



o 
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return value is also described: 



o 



'o 



VAR par.ni type) C 0« description of last parameter 

return.pars type; { description of return parameter 



The "?? PUSH (LISTEXT :« CN I ?? / ?? POP ??«• directives way t 
be used around some or all of the common deck calls. | 



4.* CD!ifiMI-Q££lL.UiaUI 

Common decks containing source code contain a one line 
description of the deck, prologue documentation, the source code, 
and a *callc to alt common decks necessary to compile the source 
code in Isolation (assume a CYBIL module only calls this comron 
deck). Directives to PUSH/PCP the LISTEXT toggle must be used to 
control the listing. LISTEXT Is used to ensure that the one Hne 
deck description is listed* and may be used to control listing of 

_ the called common decks (listing is controlled by the "LO" option 

J!L on the CYBIL compiler command). 



The format for source code common decks is as follows* 
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ggtxxxx 

COMMON 

?? NEWTITLE :» 'ggtxxxx - short description* ?? 

?? PUSH (LISTEXT »• OFF) ?? 

I ggtxxxx - short description (single line), 

?? POP ?? 

c 

{ Prologue documentation 

{ . 

t . 

{ . 

{ (continuation of prologue) 

< body of common deck > 

?? PUSH (LISTEXT :» ON) ?? ( optional ) 

*cal|c comdeckl ( common decks necessary to compile ) 

*cal I c comdeck? 



• • • 
♦callc comdeckn 
?? POP ?? 
?? OLDTITLE ?? 



( optional ) 



An EJECT may be used with the NEWTITLE directive* for example: 

?? NEWTITLE :» »ggtxxxx - short descr ipt ion»> EJECT ?? 

Note that page width should not be set in common decks. 

The format of other common decks Is shown with the description of 
the common deck content in the following sections. 



o% 



4.4.1 "B" - PINOER DIRECTIVES 



The "binder directives" common decks contain Binder directives 
for the source OPL decks which reference it. This deck Is used 
for the build process and is described in more detail in the 
Installation Process IDS. 



4.4.2 "C" - COMMON OECK CALLS 



The "common deck calls" common decks are used to provide a 
convenient way to call several common decks which are closely 
related with a single call. These common decks do not call other 
C type decks* and should not significantly overlap in content. 



o 
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Vw^ 



The format for these decks Is as follows: 

ggCxxxx 

COWPON 

?? NEWTITLE s* 'ggCxxxx - short descr ipt lon» , EJECT ?? 

I DESCRIPTION* 

t A description of the how the called common decks relate. 

C ... (continue description as necessary). 

♦ cal Ic comdeckl 
*cal Ic comdeck2 



*ca I Ic comdeckn 

4.4.3 "0" - CONSTANT ANO TYPF DECLARATICNS 

The "constant and type declarations" common deck contains CYBIL 
CONST and TYPE declarations* followed by a *callc to all of the 
declaration common decks necessary to compile this common deck in 
isolation. VAR declarations are also allowed, but in most cases 
should appear In a source code module l"H" type decks) rather 
than in this type of common deck. This type of deck Is used by 
modules dealing with the same types of data. The description In 
the prologue should explain the relationship between the 
declarations < le. what are they for, how are they used, and/or 
why are they grouped together ?)• 

"D" type decks follow the format for source code decks described 
previ ous ly. 

4.4.4 "G" - GROUP COMMON DECK CALLS 

The "group common deck calls" common decks are used to provide a 
convenient way to call several closely related common decks in 
aQflItfi£-ai.au£ with a single call. These common decks do not call 
other G type decks, and should not significantly overlap in 
content. The G type decks are the same as C type decks* except 
that they are allowed to call common decks In another group 
(i.e., an upper layer sharing an interface with a lower layer) 
without making the interface available to everyone via global 
(group CM) common decks. The format for these decks is as 
f ol I owst 
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ggGxxxx 

COMMON 

?? NEWTITLE :» «ggGxxxx - short de s cr ipt ion* • EJECT ?? 

i DESCRIPTION: 

C A description of the how the called common decks relate. 

C ... (continue description as necessary)* 

*caltc coradeckl (common decks in another group) 
teal I c comdeck2 



teal le comdeckn 



A. 4. 5 "H" - DOCUMENTATION HEADER 



A "documentati on header" common deck is used for procedures* 
functions and variables referenced via an XDCL/XREF interface. 
It contains a prologue block as described earlier (section 
2.3.2). This common deck must be called from the module which 
contains the XDCL defintion and from the XPEF common deck. No 
listing control directives are to appear In this common deck. 



d 



ggHxxxx 

COMMON 

f. XDCL/XREF prologue block. 

C ... (continuation of prologue block) 



4.4.6 "I" - CYBIL INLINE PROCEDURE 



The "CY8IL inline procedure" common decks contain procedure 
declarations which may be expanded inline as part of the calling 
modules rather than being called through an XDCL/XREF Interface. 
Internal inline procedures may occasionally be the most practical 
way to implement a "module" (in the Structured Design sense) due 
to performance and/or scope considerations. A procedure 
implemented in this fashion must not be dependent on the static 
chain (ie.» it must be completely self contained). 



"I" type decks follow the format for source code decks 
previously. 



described 



o 
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IKEP DIRECTIVES 

4.4.7 »L" - LINKER DIRECTIVES 

The "linker directives" common decks contain Linker directives 
for the source QPL decks which reference it. This deck is used 
for the build process and Is described in more detail in the 
Installation Process IDS* 

4.4.8 n T" - TYPE IDENTIFIERS 

The "type identifiers" common decks contain type Identifiers and 
calls to B and L type common decks. This deck is used for the 
build process and is described in more detail in the Installation 

Process IDS. 

4.4.9 "X" - CYBIL XREF DECLARATION 

The XREF declaration common deck contains a. CYBIL XREF 
declaration followed by a *callc to all of the decks necessary to 
compile this declaration in isolation (assume a CYBIL module only 
calls one XREF declaration common deck). This type of deck Is 
used by modules accessing procedures* functions or variables 
defined (with the XOCL attribute) In another module. 

X type decks follow the format'for source code decks described 
previously. 

The prologue documentation Is replaced by a call to a 
documentation header deck* ie«: 

f 

♦call ggHxxxx 
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5.0 CQfllMfi 



When coding* 
modification 
easier* 



always consider 
and Maintenance} 



the implications of 
structure code to make- 



debugging* 
these tasks 



5.1 IttlSBEftCEl 



In generel* Interfeces between Modules should be procedures or 
functions* not XOCUXREP variables. The use of explicit 
parameters Is more Illuminating than references to global data 
structures. 

The conventions to be used for procedure and function interfeces 
are defined In the CIfllt.IlBleBfiDt.aliflIL^£B£QdeDt . Hafldhflflh.. 

The OCNS Common Subroutines are to be used instead of 
self-tailored system Interface routines fie. buffer common 
routines should be celled rether then direct manipulation of 
buffer descriptor and data fields). Also* when e procedure or 
function Is defined with the XDCt attribute* e common deck 
containing the XREF declaration for the routine must be defined 
and all celling routines must reference this common deck. This 
mill minimize the exposure to system specific coding 
dependencies* eliminate redundant work and increase 
maintainabll Ity. 

Oectarations which define e specific Interface Me. layer 3A to 
layer 38) should be grouped into a common deck* thus providing a 
clear* concise interface description. 



v„y 



5.2 £££££41£i£&{£EQU££l£EUtLC.llJ2ttt 



5.2.1 PURPOSE 



Procedures end functions should be used for two purposes* 

- To provide common subroutines within s module. 

- To structure the program* thereby making the function of the 
program obvious at a high level. 
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5-2.2 LENGTH 

In aost easts* the length of ■ routine should be kept down to one 
or two pages* Anything longer becoaes difficult to read* 
understand and therefore Maintain* 

5.2*3 COMPLEXITY 

The wore eoaplex a routine is* the aore liable It is to be a 
source of errors end difficult to iapleaent* aodlfy and aalntaln* 
Cyeloaatlc eoaplexlty Is a concept which has gained soae 
•cceptanca within Control Oata Corporation* ACSO defines the 
cyeloaatlc complexity of a Module as the sua of "IF*. "WHILE"* 
"FOR" and "REPEAT" stateaents ♦ i* For e aore detailed analysis 
of the eoaputatlon of eoaplexlty* see "Structured Testing" by 
Thoaas J* NeCabe. 

In the Interest of Malting the complexity of routines and 
therefore increasing readability and Maintainability* the 
following general rule should be followed! 

A routine should not have a cyeloaatlc complexity of aore than 
twenty* 



5.3 Qaln DECLABallflttS 

A declaration should always be declared at the Inner-Most 
procedure level possible. 

Avoid the use of type INTEGER; few variables require subranges 
that large. Ordinal and subrange types of the appropriate size 
provide better variable range cheeking end docueentation* 

5** £LflX-£UattlflH 

Avoid use of the flQC function. Code should not be Meaory 
location dependent. 
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5.5 £l££_mi£fi£*Ii 



Covtr all end costs with ELSE being used to cover -unplanned* 
esses. If the ELSE clause In the CASE statement Is Missing* the 
CYBXL compiler will not generate Holt checks for CASE entries 
outside the range of the specified CASE label* 

5.6 £££££2£I£&2. 

In compound arithmetic* conditional or relational expressions* 
parenthesis should be used to denote precedence. Oo not depend 
on the language operator precedence rules. 

Compound boolean expressions should be constructed such that 
evaluation of the expression terminates as quickly as possible 
Tor the typical case. 

Use boolesn expressions Instead of IF statements to conditionally 
set a value to TRUE or FALSE. 

equality »» (a«b)l (Instead ofl 

IF a • b THEN 

equality t* TRUE? 
ELSE 

equality i« FALSE} 
IFENOI 






) 
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a 6.0 COOE READABILITY 



6.0 CQIiE..EEADAaiLlII 



CyBFQRN takes care of most of the formatting necessary to 
maximize code readability. The folloMlng sections describe some 
other techniques for increasing code readability. 

6.i eqbhbt gfsiAiEflans 

Structured statement pairs (BEGIN/END* FQR/FQRENO* WHILE/WHILEND! 
and IF/IFENO pairs are hard to natch when separated by more than 
10 lines of code* or when they are nested* 

For structured statements* labels are al toned and should be used 
in these cases to assist In Hatching the pairs (as well as for 
documentation purposes!. 

For examples 

/search.symbol. table/ 

FOR I J« 1 to 10 do 

FORENO /seareh.symbot. table/; 

For IF/IFENO pairs* comments imitating labels may be used* In 
this case* there should be no blank line following the Initial 
comment (normally* a blank line should be on either side of a 
stand alone comment!* 

For examples 

t Check eommand file status* 

IF c ommand.fi I e.stat us * success THEN 



IFENO; C Check eommand file status* 

Compound conditionals In an IF* FOR or WHILE statement must be 
separated at the OR/AND if the entire statement does not fit on a 
single line* At the programmer's option* the statement may also 
be separated at each OR/ANO regardless of tine length to make the 
code more readable. 



o 
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For exaaptes 

IF Ucond.a) AND (cond.b)) C IF ((cond.a) C 

OR (cond.c) THEN AND (cond.b)) C 

(or! OR (cond.c) THEN 

IFENOI 

IFENO? 

6.2 DECusmnas 

Where a declaration contains a list of (tens it aay be helpful to 
list each elcaent on a separate line* Defining ordinals* sets or 
presetting elements of an array are examples* Coaaents can be 
used to force splitting the declaration Cwhen the code Is run 
through CYBFORHJ* 

With descriptive names, e comeent with text aey not be necessary 

and blank coaaents a ay be used* \v 



x 



For Exaaplet 

TYPE 

clt$character_class ■ i I 
clcSspace.character* C 
elcSeoaaent.delial ter.character* C 
elcSstring.del ial ter.charaeter • € 
clcSdlgl t.character* C 
ctcSalpha.char acter* { 
clc$token.character* C 
clcSdl graph.token.cheracter* C 
clcSother.character C 
)I 



') 
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c 



Where readability Mould be greatly enhanced by alignment of code 
and/or comments* the CY8F0RH FNT pragmat may be used to turn off 
formatting for a specific block of code. The code must still 
start in the appropriate column* and formatting Must be turned 
back on at the end of the block of code* 

?? FHT (FORMAT t- OFF) ?? 

I Mainframe Channel Interface Intertask Message Workeodes* 



?T 



CONST 

ncl.startup 
■ei.output.co*plete 
mel.input.reeelved 
mei_dota_avei I able 
■ei.error.eneountered 
mcl.shutdoMn 
raci. statistics 
mci.report.stati sties 
mei.regulation.change 
mei.timer.explrotion 
mcl.log.. message 
FMT (FORMAT i« ON) ?? 



• 0501(16)* 


C 


Specif 


• 0502(16)* 


c 


PP has 


» 0503(16)* 


f. 


PP has 


« 0504(16)* 


c 


Oata i 


• 0505(16)* 


c 


An err 


- 0506(16)* 


c 


End pr 


> 0507(16)* 


c 


Sender 


• 0508(16)* 


c 


Announ 


• 0509(16)* 


c 


New re 


• 050a(16)» 


c 


Respon 


• 050b(16)I 


c 


Messag 



Ic MCI card 

successful read 

successful write 
s available for transfer 
or Mas found on a write 
ocessing 

requests statistics 
ce statistics response 
gulatlon level In effect 
se timer has expired 
e Is to be logged 



6.3 aiatt&-LIH£S 



A blank line should precede and 
Additional blank lines should 
to enhance code readability* 
consistently within e module* 



follow all stand alone 

be used et the coder's 

Blank lines should 



comments* 

discretion 

be used 



It is helpful to insert blank lines 
EXIT statement to indicate a break In 



after each RETURN* 
the program flOM* 



CYCLE or 
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A 1.1 ESQ££QU££i 



?? NEWTITLE :» 'Bypass Configuration Command Processors* ?? 

?? NEWTITLE :» 'PROCEDURE CXOCL* #GATEJ cmd.bypass.conf Igura t i on»> EJECT ?? 

PROCEDURE cmd.bypass.conf igurat ion 

PURPOSE* 

process the bypass_conf iguration command. 

DESCRIPTION! 

The global variable bypass.confi g_f I ag is set to indicate to 
the Configuration Procurer that an operator wishes to enter 
the configuration manually. 

COMMAND FORMAT* 

BYPASS.CONFIGURATION (3YPC) 

GLOBAL DATA MODIFIED: 

bypass.conf ig_f lag - set to indicate that configuration file 

processing should be bypassed* 
command. source - the address of the user that issued the 
command is saved 

p»PR0CE0URE CXOCL, #GATEJ cmd.bypass.conf igurati on C C 
parameter.l 1st: ostSstringj 
V4R pvt: cl tsparameter.value.tab le; 
VAR response.codet condl tion.code; 
VAR response: cltSstatus); 



v./ 



?? PUSH (LISTEXT :» ON) ?? 
*ca I Ic metmdu 
*cal Ic mexgsa 
?? »OP ?? 



4-VAR 

error.msg: CSTATIC1 string (39) :« t 

'No parameters expected after command.' CAT 
mec$end„of - l Ine. 
j. task: task.ptr; 
??^JECT ?? 



f 



o 
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f. Begin CH0.8YPASS .CONFIGURATION. 

response. condi tion :■ NIL; 

{ Check for parameters. No parameters are allowed. 

IF parameter.! 1st. size <> THEN 
response.code :» par.err.ccode; 
response. normal :» FALSE; 
gen.data.f leld (r esponse. condi tlon# *error_msg» iSIZE 

(error_«sg)» char.octet )> 
RETURN? 

IFENO; 

task :■ NIL; C indicate current task.ptr to be used 
get.source.address (command.source, task); 
bypass.conf I g_f lag J» TRUE; 

response.code :« ok_ccode; 
response. normal :» TRUE} 



1 vJ- ?? aL0 



END cmd.bypass.conf i gurati on J 
TITLE ?? 
?? NEWTITLE :- 'PROCEDURE CXDCL* fGATEJ cmd_bypc«» EJECT ?? 



PROCEDURE cmd.bypc 

PURPOSE: 

This is the command processor for the bypass.conf 1 gurati on 
command alias* bypc. 

DESCRIPTION: 

Cmd.bypass.conf iguration is called to process the command. 

COMMAND FORMAT: 

Pefer to the bypass.conf iguration command description. 



*c 



PROCEDURE CXDCL* #GATE1 cmd.bypc C € 
parameter.l 1st: ostsstrirg; 
VAR pvt: cl tsparameter.value.table; 
VAR response.code: condi ti on.code; 
VAR response: cltSstatus)? 
?? SKIP :« 4 ?? 
C Begin CMD_8YPC. 

cmd.bypass.conf i gur ation (par ameter.l 1 st> pwt» 
response_code» response); 
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PRCCENO cnd.bypc; 

?? QLOTITLE ?? 
?? CLDTITLE ?? 



^ 



I 
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A 1.2 ;CJ!.IX££.Cflfl!lQ!l-Q££Ii 

* 

CMCTREE 

COMMON ' 

?? MEWTITLE :» 'CMCTREE - Tree Management Definitions 1 , EJECT ?? 

{ DESCRIPTION! 

C CMCTREE contains calls to the common decks which contain 

i tree management definitions. 



<& 



*cal Ic CMDTTRE 

♦ cal Ic CMXPEXC 

♦ cal Ic CMXPFFN 
♦callc CMXPFIN 
♦cal Ic CMXPFNC 
*cal Ic CMXPFNF 
♦cal Ic CMXPFNX 
♦calic CMXPGRO 
*cal Ic CMIPINT 
♦cal Ic CMXPPIC 

?? OLOTITLE ?? ' 

A 1.3 !!Ii;_LIP£.CJlflfiQSi-Q£tll 



• 



CLDINT 

COMMON i 

?? PUSH (LISTEXT :» OFF) ?? ! 

< CLDINT - Convert String to Integer Result. S 

?? POP ?? ' 

c 

C DESCRIPTION: 

f The TYPE declaration for the result of the CIP.CONVEPT. 

{ INTEGER.TO.STRING procedure is defined. 

TYPE 

cltSinteger * record 

value* integer, 

radixt Z •• 16, 

radi x.specif led: boolean, 
recendj * 



'<3 
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CLHCS2I 

COMMON 
{ 

c 
<• 
c 

€ 

< 
i 
i 

f 



PROCEDURE clP.convert.strlng.to.lnteger ALIAS clpcs2l 

PURPOSE: 

This procedure converts the string representation of an integer 
to an integer. The string representation may contain a leading 
sign (♦ or -) and/or a trailing radix enclosed in parentheses. 



CALLING FORMAT: 
(♦callc clxcs2i) 
CLP_CONVERT_STRING_TO_INTEGEP 
CLPCS2I (STR, INT, STATUS) 



(STR, INT, STATUS) or 



< 



STP: (input) This parameter specifies the string to be converted. 
INT: (output) This parameter specifies the converted Integer 

value along with the radix in which the integer was 

represented. 
STATUS: (output) This parameter specifies the status of the 

request. 
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CLXCS2I 

COMMON 

?? NEWTITLE :» 'CLXCS2I - Convert String to Integer' ?? 

?? PUSH (LISTEXT :» OFF) ?? 

{ CLXCS2I - Convert String to Integer. 

?? POP ?? 

< 

♦call clhcsZi 

PROCEDURE CXPEF1 cl p.conver t.str 1 ng.to.i nteger ALIAS •clpcs2i» ( f. 
str: string T*)j f. I: string to be converted 
VAP int: cl t$ integer J I 0* converted integer value and radix 
VAR status: cltSstatus); C 0: request status 



?? PUSH (LISTEXT :» ON) ?? 

*cal Ic cl dint 

*cal tc cl dstat 

?? POP ?? 

?? OLOTITLE ?? 
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CLXCS2I 

COMMON ... 

?? NEWTITLE »• 'CLXCS2I - Convert String to Integer* 1* 

C CLXCS2I - Convert String to Integer. 

?? PUSH CLISTEXT • ■ DM) ?? 

C 

♦cell clhes2l 

PROCEDURE CXREF1 clp.convert.strlng.to.lnteger ALIAS »clpcs2l« ( t 
strs string C*»J C I* string to be converted 
VAR lnt« cltSlntegerl t Ot converted Integer value and radix 
VAR status* cttSstatus); C 0* request stetus 

?? PUSH (LIST «• OFF) t? 

*calle eldtnt 

♦callc cldstat 

?? POP tt 

?? POP ?? 

?? OLOTITLE ?? 
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industry abbreviations and programming language names 
even though they are not included in the following 



A- A 

AP 

BERP 

BERR 

8TF 

BVT 

CO 

CONA 

COCNET 

CEP 

CEPIO 

CIB 

CIN 

CNN 

CPOU 

OCB 

OCI 

OCNS 

01 

OVH 

ESCI 

FRU 

FTP 

HOB 

HOLC 

HSB 

HTB 

HUB 

IC8 

IOU 

IOSS 

ISB 

ITB 

ITF 

IVT 

LIN 

NCI 

MDI 

H-E 

HP8 

HTI 

NDI 

NHP 

POU 



Application to Application 

Application Process 

Background Processing 

Bus Error 

Batch Transfer Facility 

Batch Virtual Terminal 

Col 1 islon Detection 

Control Oeta Network Architecture 

Control Data Distributed Communications Network 

Connection Endpolnt 

Connection Endpoint Identifier 

Communications Interface Nodule Instruction Block 

Communications Interface Nodule 

Cache Neaory Nodule 

Channel Protocol Oata Unit 

Device Control Block 

Oata Concentrator Interface 

Distributed Communications Network Software 

Oevice Interface 

Oevlce Nanager 

Ethernet Serial Channel Interface 

Field Replaceable Unit 

File Transfer Protocol 

Downline Interface Block 






HOLC 
High 
High 
HOLC 
HOLC 



Level Oats Link Control 

Speed Bus 

Trunk Identification Block 

Upline Interface Block 
Internal Control Bus 
Interface Oata Unit 
Input/Output Subsystem 
Internal System Bus 
Internal Transfer Bus 
Intereetive Transfer Facility 
Interactive Virtual Terminal 
Line Interface Nodule 
Nalnframe Channel Interface 
Nelnframe Device Interface 
Nanagement Entity 
Naster Processor Board 
Nelnframe Termlnel Interface 
Network Device Interface 
Network Host Products 
Protocol Oata Unit 
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PMH Private Meeory Hodule 

SAP Service Access Point 

SAPID Service Access Point Identifier 

SOU Service Dote Unit 

SHU Systea Main Heuory Nodule 

SSft Streea Service Routine 

SVN Service Module 

TOI Teratnal Device Interface 

TVA Two Vay Alternative 

TViS Tmo Way Slaulteneous 

URO Unit Record Device 

URI Unit Record Interface 

VTP Virtual Temlnel Protocol 
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Error messages represent a very Important* though often 
neglected* Interface between software and the user* Proper 
attention to producing polite* correct and clear error messages 
can do a lot toward improving the overall usability of the 
system. The following general principles are to be observed In 
designing error messages* 

- Messages must be formattable for 72 character displays.. 

- The purpose of an error messsge Is to inform the user how to 
correct a problem. 

It helps to view error messages as prompts! not "this Is what you 
did wrong" but "this Is how to do I t right." Messages should be 
phrased positively. The words "IUE6AI", "INVALID"* and "SYNTAX" 
are specifically not permitted in messages. Of course* there are 
other ways to phrase unhelpful* negative messages} but these 
three words are singled out for extinction for being so 
frequently seen in the company of usability offenders. 

• A single message should diagnose a single error. 

For example* if the meaning of message Is "more than seven v / 
characters or leading non-elphabetlc character or null 
Identifier** It should be three messages. Usually* the code must 
make three separate tests* so it Is easy to be precise. An 
exception is when a common deck returns an error status which 
could have resulted from sever.al different conditions. 

- An error messege is friendly If It Is business-like and 
informative. 

Cute* funny* or flippant messages ere to be avoided* as they 
seldom dlegnose eccurately and always wear quickly. Messages 
should be directed et the process and not the person. 

- Messages must be written plainly* using terms already known to 
the user. 

Messeges should use terms which are either self-defining or 

natural to the process. All words should be part of the external 

user interface* tike "file nine" instead of "IFN" (unless LFN is 
an external parameter!. 

- Messages must be written in English. 

Messages should follow normal rules for English grammar and 

punctuation* although "pidgin English" (the omission of selected ^ v 
subjects* verbs or objects in the interest of brevity where the ^J 
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meaning is clear) Is acceptable. Use upper and lower case as 
they Mould normally be used In the English language. Upper case 
should be used to distinguish variable parts from normal English 
Mords. Ending punctuation should be used* It Indicates to the 
user that the message Is not continued on the next line and adds 
to the readability of the message* Messages should not be 
written In octal* or In other forms of scientific notation* Note 
that the asterisk Is not an English punctuator* 

• Messages should be self-contained* 

If you need to tell a story* tell the whole story* Avoid 
references* as they are difficult to keep up-to-date and are 
often no more helpful then a good one-tine message would be* 

- Error messages should point directly to the source of the 
trouble* 

For example* "File not found** Is better put as "File XYZ not 
found*** "Expecting comma or period after ABC*" Is much clearer 
than "Syntax error."* In general* the technique of echoing back 
part of the user input as part of the message is better then the 
use of internal names or parameter keywords which the user may 
not recognize. 

- Interactive error messages should appear as soon as possible 
after an error is committed* 

Each Interactive Input should be completely and fully validated 
as soon as It is received* In no event should a user be led down 
the garden path to enter a long series of Input only to be 
advised that It is all wrong because the first pert was wrong* 

- No messages at all should appear for trivial* correctable 
errors* nor should they be errors. 

Errors such as missing or redundant terminetors should not be 
errors at all. If a reasonable assumption cen be made as to the 
intent of an input* it should be acted upon as though It were 
"valid". No error diagnostic should be produced for these cases* 
If it Is not perfectly clear what assumption was made* the 
assumption was probably not reasonable to begin with* 

- An error message must clearly signal that an error has 
occurred* 

An error message must not be phrased In such a way as to be 
confused with a merely informative message* Also* a message 

should Indicate the gravity and extent of the error* as when an 
error in e list inhibits processing of the remainder of the list. 
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The purpose of this section is to describe the conventions that should 
generally be used by designers of procedural interfaces* 

EU££Q££ 

The purpose of. the following conventions is to achieve a software system 
which exhibits the beneficial characteristics of being understandable* 
reliable* efficient* Maintainable* etc* 

££H£RAL-£lllLflS£m 

o Select simple straightforward Interfaces. Complex interfaces* those 

whose description contain «and»» »or , » and conditional clauses* Impair 

understanding of the function* If there Is not an evident choice between 

a single complex Interface and multiple simple interfaces* choose the 

£K^ simple Interfaces* 

I - A single interface encompassing multiple intrinsic functions* whicl. 
cannot be performed In conjunction with one another* unduly Increases' 
validation overhead* A simple Interface for each intrinsic function 
is preferred* 

- If the intrinsic functions encompassed by a single interface require 
different degrees of user privilege* each Intrinsic function should 
be a single simple Interface* 

- The combination of multiple intrinsic functions Into a single 
Interface is practical when the functions can logically be performed 
In eonjuctlon with one another* 

o Input parameters should be validated early in the processing when the 
correlation between the potential error and the actual parameter is 
readily identifiable. This aids In ensuring that diagnostics accurately 
reflect the cause of the error* 

o Wherever feasible* delegate the error prognosis to the requestor fl.e.» 
return control to the requestor with accurate information when an error 
is detected)* 



o 



o 'Refrain from exposing internal structures or concepts via externalized 

interfaces* Before externalizing internal structures or concepts rate 

the probability of change and the user consequences Ire-code* 

re-compilation* etc*) If In fact the external izatlon changes* 
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INPUT PARAMETER CONVENTIONS 

Input parameters In the following conventions are formal parameters in 

the Xref procedure declaration* 

o Declare all input parameters to be <va1ue parems>* 

- If for any reason Input parameters are declared as Reference 
params>* the actual parameters must be moved to local automatic 
variables prior to validity check and subsequent usage* Further* ail 
Input parameters declared as Reference params> must be moved before 
mi validation or usage occurs* 

o All Input parameters must be checked for validity with explicit language 
statements Prior to use. In fact ill input parameters should be 
validated before «* parameter Is used. 

o Input parameters which specify subfunetion or function option should be 
discrete parameters (i.e.* should not be a field of a record). 

PARAMETER TYPING - CYBIL USAGE 

Parameter types are declared in terms of the CYBIL pre-defined types or. 
type identifiers which resolve to the pre-defined types. ^J 

The first inclination should be to declare parameter types as type 
Identifiers* declaring their ultimate types with txs.t declarations. 

- The language and general ease of use dictates that ordinal* array, 
and record parameter types be declared as type identifiers* 

- For parameter types other than pointer and cell* before selecting the 
pre-defined types consider the following! l) If the concept of the 
parameter is used by more than one external Interface* use a type 
Identifier} 2) If the parameter type has any significant probability 
of change, use a type identifier? and 3) If the parameter identifier 
cannot accurately convey the purpose and intent* use a supportive 
type Identifier. 

Ordinal or boolean parameter types are preferred over Integer or Integer 
subrange when declaring subfunetion or option parameters* If the scope 
of a boolean parameter type has any significant probability of exceeding 
binary* that parameter type should be declared as an ordinal type. 

Take advantage of the self documenting aspect of ordinals by using 
descriptive ordinal type Identifiers and ordinal constant Identifiers on 
parameters. 

An ordinal type should be consistent within Itself* that Is* there should 
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be on evident relationship among the ordinal type Identifier and tl 
ordinal constant identifiers* 

o An ordinal type should support only one concept* 

o Before utilizing an ordinal subrange in an interface, consider defining a 
new ordinal type. If an ordinal subrange is the appropriate choice* 
declare that subrange as a type identifier. 

o Integer subrange Is preferred over Integer when declaring numeric 
parameters. Further* the Integer subrange should be declared as a type 
Identifier and the bounds of the subrange should be specified with 
descriptive constant (CONST) declarations. The low bounds* If zero or 
one* need not be specified with constant declarations. 

o Use a constant ICQNST) declaration to specify length of string type 
parameters. 

o Set type provides a mechanism by which multiple subfunctions or options 
may be discretely specified with a single parameter. This use of set 
type is preferred over the use of codes each of which specifies a 
combination of subfunctions or options. 

o Array type parameters will provide a convenient* useful* efficient 
Interface In the bounds of the convention objectives If the following^ 
criteria is achieved t 

V 

- The function ean be logically performed on multiple arguments of the 
same type Carray components) with one request} or the function can 
logically generate multiple values of the same type with one request. 

- Each array component can be acted upon (or generated) ir> absence of 
all other components. 

- The result of the function relative to one component has no effect 
on the result of the function for any other component. 

- The order of the components has no bearing on the Individual 
results. 

o Record type parameters provide a convenient* useful interface in the 
bounds of the convention objectives If the record can be thought of (In 
the user's sense) as a single unified entity (I.e.* no field of the 
record has particular significance in absence of any other field). If a 
field does not meet this criteria* It should be a discrete parameter. 

- A record parameter type will simplify interfaces and be convenient 
when the record Is also a parameter of other external interface 
procedures and does not require user Intlal izatlon or manipulation of 
contents - the user need only be concerned with the concept of the 
parameter* its structure and contents are transparent. 
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- Each field should have an evident consistent relationship with the 
other fields of the record. Merely being parameters of a function 
does not.establish the unified relationship. 

- If a field by itself has particular significance* that field should 
be a discrete parameter. Fields which are subfunction or option 
parameters to a function have such significance and should be 
discrete parameters. 

- A record type parameter should not contain fields which are 
superfluous to the execution of a function. Each field of an input 
parameter record should be essential to the execution or the function 
(i.e.f each field should be a required argument). Each field of an 
output parameter record should contain a value returned by the 
function. 

- Record type parameters may contain superfluous fields if the fields 
are present for symmetry with other functions supporting the sa*e 
concept. Use of this direction to justify superfluous fields 
should be minimized - superfluous fields mill Impair user 
understanding and result in excessive re-work at maintenance and 
extension time. 

• System architecture may dictate that some seemingly superfluous 
fields appear In a record to reserve space for data used internally 
by a function In support of other functions relating to the san^) 
concept - this Is Justifiable. 

- A record type parameter should be solely an Input parameter or solely 
an output parameter (i.e.* a record should not contain some fields 
which are input parameters and other fields which are output 
parameters). 

o Input parameters should not be pointers (CYBIL pointer type) to internal 
objects - validation of the pointer objeet would be virtually Impossible. 

o Pointers to internal objects (output parameters of CYBIL pointer type) 
must not be returned to the user - unnecessary exposure of Internal data 
will result if such pointers are returned. 

o Pointer type formal parameters should be declared only when the pointer 
object of the actual parameter can take one of several types (I.e.* the 
pointer object type Is ofll known at compl le-tlme* but Is resolved at 
execution-time). The formal parameter pointer type should ultimately 
resolve to '*cetl*. 

o Packed structures* adaptable types* and bound variant records have some 
applicability in external Interfaces* but their use should be the 
exception rather than the norm. 
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££Q£&Att.UBF ftBl-CQtttt&lilima 

aECH-HAIlIiia-CDamillQtlS 

Oeck names hove the following fornti 

PPCZZZZ 
where 

PP » two character product Identifier 
C » one character indicating deek class 

ZZZZ ■ one to four character mnemonic for uniqueness within 
product 

Allowable codes for deck type are as follows* 

H * CYBIL code nodule 

X » CYBIL xref declaration (common deck) 

• CYBIL type and const declarations (common deck) 
H * Documentation header (common deck) 

1 » CYBIL Internal In-line procedure (common deck) 

Note that deeks of type M must consist of fixiftUl 2Lt module (compilation 
unit). 

When converting to the source code utility (SCUl all XREF declarations, 
documentation headers and module decks can be renamed. The new deck name 
will have the same three character prefix but the suffix (ZZZZ) can be the 
full name (up to 28 characters) of the Item contained In the deck. 

UfiJUQUiJlEiH-USAfiE ' 

Common decks are restricted to four classes of usage* 

- XREF declarations to be used by modules accessing procedures or 
variables defined in another module* 

- TYPE and CONST declarations to be shared by modules dealing with the 
same data types or constants. 

- Documentation header text describing an Interface. A comwon deck of 
this type must be called from the module which contains the XDCL 
definition of the interface being described. 

' - Procedure declarations whleh may be expanded in-line as P^tQf 
calling modules! as opposed to being called through an XCCL/XREF 

O Interface. Internal In-line procedures may occasionally be the most 
practical way to implement a -module" (In the Structured Desigr , 
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sens*) due to performance and/or scope considerations, m commc 
decks of this type are considered Internal interfaces and must be 
documented accordingly. A procedure Implemented In this fashion must 
not be "dependent on the static chain* I.e. It must be completely 
self-contained. 

£QU3Qa-QE£&-CatiIiai 
DOCUMENTATION HEADER 

The procedure documentation header consists of CY8IL comments which 
describe the procedure* Its calling sequence and parameters. The general 
format for the procedure documentation header is as follows! 

123456789012345... 

1K> 

2)C The purpose of this request Is to ••• 

3)C whatever this request does. 

4)t> 

5J{ XXPSREQUEST.NAME (FIRST.PARAM* ...» 

6)C LAST.PARAM1 

8){ FIRST_PARAM» (input) This parameter specifies ... f\ 

o)C whatever this parameter specifies. w 

10)0 

IDC LAST.PARAMJ (output) This parameter specifies ••• 

12K whatever this parameter specifies. 

13)0 

where* 

line It blank comment line 

tine 2» Indent 4* describe the purpose of the request 

line 3i Indent 2: for purpose continuation* if necessary 

line 4« blank comment line .......... 

line 5« Indent 8* request calling sequence! use ell capital lettersj 
parameter names must be the seme and must be In the same 
order as In the XREFed procedure declaration 

line 6t Indent 10 for parameter continuation If necessary 

line 7* blank comment line 

line 8t indent is describe first parameter? specify whether it is 
Input* input-output* or output 

line 9: Indent 8* for parameter description continuation* If necessary 

line 10* blank comment line separates each parameter 

line 13i blank comment line 

Also* mhen listing parameters one should strive to list ell Input 
parameters first followed by input-output parameters followed by all ««Jput 
parameters unless there Is an obvious symmetry with other requests tnat 
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f 
would be violated. The status parameter* If present should always be the 
last oarameter on every request. 

Each data structure Mill include a documentation header consisting or 
CYBIL comments which describe what the structure is for and how it Is used. 
The general format is as described for the "purpose" section of the 
procedure header. 

XREF DECLARATION COMMON OECK 

The XREF declaration common deck contains a CYBIL XREF declaration 
followed by a *ealle to all of the TYPE or CONST declaration common deeks 
("0" deeks) necessary to compile this declaration in isolation (assume a 
CYBIL module only calls one XREF declaration common deck). 

It is very important that all XREF declaration common deeks perform 
♦callc's (Instead of *call) to necessary decks. This prevents duplicate 
definitions of identifiers In the caller's CYBIL module. 

Example: 

AMXREWO V> 

COMMON 

PROCEDURE CXREFJ amp$rew ind( fl 1 evident If I er: 
amtSf lle.identifier; 
wait*ost$wait; 
VAR statustostSstatus); 

?? PUSH (LIST f OFF, LISTEXT:-ON ) ?? 
*eal Ic amdf Id 
♦callc osdwnw 
♦ cat tc osdstat 
?? POP ?? 

TYPE / CONST DECLARATION COMMON DECK 

The TYPE / CONST declaration common deck contains CYBIL TYPE and/or 
CONST declarations followed by a *callc to all of the declaration common 
decks necessary to compile this common deck in Isolation. 

It is very important that the declaration common decks perform ecallc's 
(instead of *call) to common decks. This Prevents duplicate definitions of 
identifiers in the caller's CYBIL module. 

Example* * 

) 
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AHDNANE 
COHMON 

TYPE 

amtSlocal.f He.name ■ ostSnamej 

♦callc osdnaae 

EXAMPLE OECK 

In order to be certain that Interfaces provided for the end-user or 
other functional areas are specified accurately and consistently* each 
contributor should produce an example compilation unit that includes 
references to all type and procedure declarations he/she is responsible for 
and an example of the usage of each Interface. By compiling all 
deelaratlonsf the checking logic of the compilers will aid accuracy and 
consistency? by trying examples of the Interface* the contributor mill gain 
a feeling for the efficacy of the interface. 
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This document specifies the CYBIL coding conventions suggested for the 
CYBIL users* There are several general alms of coding conventions which 
underlie all of the specific proposals that folio** 

1. There are a variety of routine* mundane aspects associated with writing 
programs* a set of coding conventions remove from the programmer 
trivial decisions relating to module format* name generation* etc. 
thereby leaving more time to concentrate on Important matters* 

2. The primary purpose of documentation and the readability of source code 
Is to help someone other than the developer understand what is going 
on* 

3* During the lifetime of a large software product like an operating 
system or a compiler* the average developer will come in contact with a 
large number of modules written by and maintained by many other 
programmers* A consistent set of coding conventions helps the 
programmer "feel at home" with a new module and therefore Is able to 
begin doing useful work sooner* 



C 



To as great an extent as reasonable* all coding conventions should b' 
generated and reinforced by automated methods* 



5. Source eode is the ultimate documentation of any program* particularly 
a program written In a higher level language such as CYBIL* Therefore* 
In all CYBIL programming* a consistent emphasis should be placed on 
producing lucid* readable* self- documenting code* 

6* All commentary In the source code should be written so that It* a) only 
provides information not readily apparent from reading the code and b) 
is of a sufficiently algorithmic nature such that it rarely* if ever* 
becomes obsolete as changes are made to the eode* 

USAfi£-0£-l-SOU£CtLCJia£-EIl£fl4IIEE 

The major software tool for generating and enforcing CYBIL coding 
conventions should be the source eode formatter ICYBFORH)* 

US£-C£.tlftIL 
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Use block structure to articulate program structure* a decleratlon 
should always be declared et the "lowest" level possible* 

Do nal «*• the static chain* in general a procedure should only 
reference arguments* its own automatic variables and static variables* 
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In general* Interfaces between nodules should be procedures o. 
functions* not XDCL/XREF variables* 

Always use~lebel names that describe the process being performed by the 
structured stetement to which the label refers* 

, Always repeat the label In the terminating statement of a structured 
statement (the formatter will do thls)t e.g.* 

/sesrch_symbol..table/ 
for I » lto 10 do 

• • • 
forend /search.symbol.tabte/l 

. In general avoid the use of type INTEGER! few variables require 
subranges that large. 

. In declarations of procedure parameter lists* always seperate each 
formal parameter with a seaicoton marking each with a VAR or "absence of 
VAR N as appropriate. 

. Always declare alt Input parameters before all output parameters unless 

there Is an obvious symmetry that would be disturbed* 



-n • Cover jj.1 end cases* CASE statements should cover all statements with 
* ' ELSE being used to cover "unplanned" cases* ^ 



. Procedures and functions should be used for two purposes: I) 
"subroutines"* 2! to "structure" the program thereby making the function 
of the program obvious at a high level. 

. Arguments to procedures should also be used for two purposes! l) 
"subroutine parameters"* 2) as documentation which allows the reader to 
see all data referenced by the procedure by looking at the procedure 
call statement. In the latter case* the formal and actual parameter 
names should be the same. 

. Trailing comment delimiter of •>• should be used whenever reasonablet 
I.e.* use of EOL as a comment delimiter Is discouraged* 

. In compound arithmetic* conditional or relational expressions* use 
parenthesis to denote precedence. Do not depend on the language 
operator precedence rules. 

• Avoid the #L0C function like the plague* 
US£.0£aHE-£tffiLlSa.UafiUAS£ 

The Hey to making programs readable is the usage of meaningful* 
non-cryptic English names for all CYBIL constructs; specifically! 



o 



\y 



o 



! 



CVBIL Handbook 17 ° 

O ' When na.lno t y D . .„ At' 06 ' 01 

consider ?h. ,de "tlflers , nd „ REv * M 

*" ' • "?• «:'?- ^./«.--- «... > 

TVPE - n0C the d «cl .ration,- 

"••'Jmm lJli° r ' record 

recend7 ' IOad -"«P-optlons, 

«oad map.option, . reeftpH 
fl 'M>a«e i f | l# ' ec ord 

options t fan I-?"*' 
recend; Ct,, »"othlng>, 
VAR 

*y-progra« * Drao< ... , 

... Pr09r "- d «*crlptor, 
•Ur.or Mi , old-| ■ 

• Procedure and , '•-»•■• «• "10ADMAP», 

•.rf.r.. r ; 8nd '— "« »«M should descr.be J 

"icrlbe the procei. »•. 

»«'-t.r.d .t. - ..:: t ";, .«•;.•;•;» *«•• r« n .H„ n btI 

;fr;— .,;i t :': f ; ,,,r ' -• r ' ' - " - 

O L> o«»s are a powerful - I 

powerrul documentary .I*. ■ 

•"«.-...„.„ t h ,„ f)n , t .. d ef ; mE "-»• -4 

" f,,e -*-ttch then ' ! 

the" J?,"." *** «"Ph.slzed too .► 

The system ni H i nn e,d »»■"»«$ " W| 

System Inter?.** J? B convention f a , »,. 
'•"try-p.?;^ - ;; *tjnd.rd ISIS). '^•"•J '"t.rf. ce$ | $ „. , 

8 t0 *** '••Icing 



o 



^L.y 



o 



CYBE» IMPLEMENTATION LANGUAGE 
#"> CY8IL Handbook 



177 

84/08/01 
REVS H 



PPCSXXX... 



et %p • |$-« two character product Identifier for the owner of this 

name* 
C • Identifies the class of the name. 

$ -Is the special character **•• ,.._.... 

XXX » a meaningful English expression or abbreviation that describes 

or denotes the purpose of the Item being named. 

Class of Names' 

C - constant 

E - exception condition name 

F - file 

M - module 

p - procedure 

S - section 

T - type 

V - variable 

fiDOUL£-itlQ-£iQC£DUEE-UQCUflEtlIAIIDll 



Q, 



Standard documentation for each module and each XOCLed procedure or; 
function within a module should be provided. The procedure documentation 
is also encouraged for local procedures and functions as well. Care shouiar 
be taken to minimize commentary becoming outdated as changes are made to 
the code. 

NODULE <module Identifier^ 

PURPOSE! 

This should contain the purpose of the module and tne 
reasons for grouping these declarations In the module rather 
than the purpose of each procedure. 

DESIGN: . , ^ , 

This should contain an overview of the module design; I.e.* 
an outline of how It works In general terms. Usage of 
specific variables or procedure names Is discouraged In this 
description. 

procedure or function declaration^ 



O 



PURPOSE! 

This shouid describe the 

function performs rather 
NOTE! 

This should contain information 

user or maintainor. 



process the procedure or 
than the method used. 



of Interest to the 
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Each module-should be titled In the following May* 

<maJor product Identif ler>t Kcomponent identif i er>...l 
<$p><sp>tIXOCLlKProcedure Identl f I er>!<sectlon Identifier) 

for examplet 

NOS : task establisher 

CXDCL1 pmp$establ ish.task 

In general* comments should be standalone blocks describing why or what 
a sfitifti of CYBIL statements are doing. Care should be taken not to use 
comments that will become outdated by detailed changes to the code. The 
basic concept behind comments should be to provide nonredundant 
information. Comments should be preceded and followed by a blank line and 
start in the first available source character on the line. Again* remember 
that the purpose of comments is to help someone other than the original 
developer of the module understand what the module is doing. 

££H££J2UR£-AIiIi-QAIA.AIiai£UI£-CQail£^I-£flIiy£tlIlQliS 

o 

Comments should also be used to convey software or system attributes 
which are not discernable from CYBIL declarations. These comments should 
be concise and abut CYBIL declaration constructs rather than being j 
standalone blocks. ' 
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This section lists t group of programming tips to help the user make 
better utilization of the CYBIL development environment. As such. It Is 
not an exhaustive list and milt be added to as additional hints become 
known. The CYBIL Project would appreciate any other Information which may 
assist the usage of CYBIL. 

These ideas are guidelines* they should be followed only when clarity of 
code is f) Ql compromised. 

GENERAL 

o There is a significant amount of overhead associated with any procedure 

call. If a procedure Is being called fn a looping construct* It may pay 

to call the procedure once and put the loop tests Inside the called 
procedure. 

o References to variables via the static chain In nested procedures cause 
an overhead associated with that reference. In general* a procedure 
should only reference static variables* arguments and its own automatl " 
variables. 

o A copy Is currently being made of all value parameters. This 
implementation is subject to change. 

o Assignment of records is done with one large move* whllm record 
comparison is done field by field. Therefore* all other things being 
equal* It is best for performance reasons*, to organize fields within 
records with the most likely non-conforming fields first. 

o Hove structures rather than lots of elementary Items. This may require 
structuring the elements together especially for this purpose. 

o Reference to adaptable structures are slower than references to fixed 
structures because the adaptable has a descriptor field which must be 
accessed. 

o References to fields within a record require no execution penalty. 

o Repeated references to complex data structured (via pointers or Indexing 
operations) can be made more efficient by pointing a local pointer at 
' the structure and use it to replace the complex references. 

o Inappropriate use of the null string facility can be an expensive NOOP. 



P 



o 






o 



180 

CYBER IMPLEMENTATION LANGUAGE 

8*/08/01 

CYBIL Handbook REVt H 

o Initialization of static variables Incurs no run tine overhead. 

o If a record is being Initialized with constants at run time It is often 
■wore efficient to define • statically initialized variable of the same 
type and do record assignment. 

o A packed structure will generally require less space at the possible 
cost of greater overhead associated with access to Its components. This 
is because elements of packed structures are not guaranteed to lie on 
addressable memory units. 

o When organizing datt within a packed structure It Is more space 
efficient to group bit aligned elements together. 

o The STRING data type Is • more efficient declaration than a PACKED ARRAY 
OF CHAR. 

o Uhen considering alternative data structures for homogenous data the 
user should first consider ARRAYS* then SEOuences and finally HEAPs. 




f\ efficient In terms of both storage and execution overhead. 

( o The NEXT and RESET statements as used on seouences and user heaps iff 
implemented as Inline code. Whereas the Implementation for ALLOCATE ano 
FREE Is a procedure call to run time library routines. 

o Space In a heap is consumed only when an ALLOCATE statement Is executed. 
In addition to the space ALLOCATEed by the CYBIL program* • header is 
added to maintain certain chaining information. For this reason* 
ALLOCATEIng small types Incurs a large percentage overhead. 

o Code for the PUSH statement Is generated Inline and* as such, Is 
considerably faster than an ALLOCATE and FREE combination. 

o For efficiency and maintainability reasons the use of #L0C should be 
avoided. 

o When a definition contains a number of 'flags' or attributes* the 
following should be considered when ehoslng between BOOLEANs or a SET 



type* 

If the record Is not packed the SET will reduce the size of the 
definition 



Any sub-set of the attributes of a SET can be tested at once. 

If a single element test is desired an unpacked BOOLEAN Is slightly 
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more efficient than a SET 
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o Usage of boolean expression, Is .or. efficient then IF statements. Fo j 
example* use* 

equally *■ ta-b)J 
Oo not use* 

IF a«b THEN 

equality *• TRUE) 

ELSE 

equality *» FALSE; 

IFENDJ 
o Rather than coding long IF sequences . CASE statement should be 
considered when using a proper selector. 

the condition evaluation for the nominal ease. 

i!"',;,!,!,!! grouped together. For example, the expression. 

X u J * » * C ♦ 2 f 

„tll produce object code using two constants C5 and 2J and two variable^ 
(Y and CI. If the expression Is rewritten* 

variables (Y and C). 

Is a benefit to define positive Integer subranges. 

diagnoseo. * omiter mvw «*•»■< • - ■» »•»«•» ■iniaitti uslno oood 

* .ij....» i.. in the source program) and then minimize, »*'"» r" _ 

;!::;::i, ( ;ml!«! ••» «;«t it .»..«». •• »*•«■ c °" ,<!,r 

the following program segment* 
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TYPE 

• • 0..10; 
VAR 

index*yt a» 

x» array Cal of integer; 
• 
y»«5;. 
index««y* 
xtindexl ««3| 

Since variables -Index- and -y- ere defined to be of type -a- Cthe 
subrange O..IO) the assignment -Index t-yj- Mill not (and need not) be 
checked for proper range even If range checking Is requested. 
Similarly, the statement -xtindexl :»3J- "III not (and need not) contain 
range checking code. If variables -y- end -index- were declared to be 
INTEGER lor some type other than the subrange 0..10I range checking code 
Mould be required. 

Any timed executions should be run after the CYBIL code has been built 
with checking code turned off. 

Certain conversion functions 1 1 .e.*SINTE6ER»$CHAR*etc. I require no ! 
execution time overhead. 

The code generated for STRINGREP Is a cell to e run time llbrarr 
routine. V. ■ 

A file should not be opened before It Is needed. As soon as a file is 
no longer needed* it should be closed. An overhead Is Involved In 
opening & closing files. Therefore* unnecessary opens S closes should 
be avoided. 

CC EFFICIENCIES 

o Pointers to strings are inefficient because the string may* In general* 
begin at any character boundary. These pointers may be created 
explicitly by assignment statements or implicitly by supplying a string 
as an actual parameter for a call by reference formal parameter. If 
possible* align strings so that they begin on e Mord boundary. 

Run time routines are called for the string operations of assignment S 
comparison Mhent 

1) Neither string Is aligned or* 

2) Lengths are knoMn and unequal or* 

3) Either or both lengths are unknown at compile time. 
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OtherMlse the faster inline code Is generated. 

It is possible to modify the buffer siie used by the CYBIL I/O package* 
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For in explanation see the ERS for CYBIL I/O (ARH2739). If there irt 
very feu accesses to a file* It may be best to select a snail buffer* 
since overall field length will be reduced* thereby Increasing total 
system throughput by decreasing swap rates* allowing aore jobs to run 
concurrently* etc* 

CI/II EFFICIENCIES 

o The adaptable string bound construct should be quoted whenever possible 
to give the compiler a clue as to the maximum length. This will often 
result In more efficient coda being generated for adaptable strings. 

o References to XDCL variables and variables declared within • SECTION 
Mill be made via the binding section and* consequently* an overhead Is 
associated with the first reference. 

o The code generator does not currently move Invariant code out of loops. 
Consequently* access to variables through the binding section within a 
loop would be more efficient if the initial access to the variable is 
outside the loop. 

» The reach of the load S store instructions on the Advanced System Is 
limited to 2**16. When using large variables the offset may become 
greater than this threshold and result In an extra instruction being 
generated to handle the large offset. This would Indicate organiztn 
the more frequently used variables first In very large user stacks. 

CM EFFICIENCIES 

o Subranges should never be any larger than necessary* Having subranges 
larger than necessary negates CYBIL's range checking* and generally 
causes less efficient code. In particular* definitions of symbols such 
as Intl6 and ulntl6» which define 16-bit signed or 16-bit unsigned 
integer subranges should be avoided. These tend to eause register 
extend operations when used in arithmetic operations* For example* if 2 
16-bit values are added* the values must be extended to 32 bits before 
adding them In order to guarantee a correct result. 

CP EFFICIENCIES 

o The UCSO p-syste» does not have an exclusive or instruction. Therefore* 
set references using the XOR operator generates a lot of code. 

o Using long Integer subranges results In less efficient code* 

o The most commonly used variables should be entered first In the list of 
—. variables for a procedure. The first n variables in a procedure are 
%j accessed by a 1 byte instruction* the others by 2 bytes. Consequently 
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large structures (I.e. trreys) should be the last variables In th= 

list. 

Using global variables In other modules should be avoided. 

Avoid FOR statements In favor of WHILE or REPEAT. They are faster and 
produce less code. 



Use base for arrays rather than 1. 
instead of "ARRAY CI., n 3". 



E.g. use -ARRAY t 



n-1 1' 



CCfi£ILUiaH-£E£liI£SltIEI 

If compilation time is a factor the following Items could be considered 
as they do affect the compilation rate. 

o The generation of Information to interface to the symbolic debuggers 
slows the compilation process. 

o The generation of stylized code slows the compilation process. 

o The generation of range checking code slows the compilation process. 

o The selection of listings slows the compilation P»; «ss. This Include/ 
the source listing, the cross reference listing and the attribute lisl* 

o Generating a source listing with the generated code included Is slower 
than If Just the source listing is being obtained. 

o Actually, for the normal CYBIL user very little can be^done to «;j r ove 
the compilation rate. However, rest assure that considerable effort has 
been expended to reduce the number of recompi lations necessary to 
produce a debugged program. 
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o Maximum number of lines in a single compilation unit Is 65535. 

o Maximum number of unique identifiers al toned in a single compilation 
unit is 16393. 

o Maximum number of procedures in a single compilation unit is 999. 

o Procedures can only be nested. 255 levels deep. 

o maximum number of compile time variables used In conditional 
compilations is limited to 1023. 

o Maximum number of error messages printed per module is 2000. 

o Maximum number of elements defined in a single ordinal list is limited 
to 16394. 

o Integer constants are restricted to 48 bits on the C170. 

CC-UifillAIlQUS O 

o Case selector values limited to less than 2**17. 

o Pointer fields within initialized packed records must be aligned for use 
within C170 capsules or overlay capsules. 

o Packed arrays whose element size exceeds 2**17 bits gets a subscript 
range error. 

Ciai.LiaUaIIflttS 

o Maximum number of lines in a single compilation unit Is 32767 when rqn 
time error checking is selected. 

o Nesting level of structured statements Is limited to 63 levels deep. 

o FOP statements can only be nested 15 levels deep. 

o Procedures may only be nested 50 levels deep. 

o Number of parameters passed to an xrefed procedure Is 127# while an 
xrefed function Is limited to 126. 
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o The reach of Jump Instructions is limited to 2**16 so the size . 
compilation units should be appropriately controlled. 

o The stack size of a single procedure ts limited to 2**15 bytes. 

o Long constants are not Included In the debug symbol tables produced. 

££_LI!!IIAIIQ!IS 

o Maximum number of lines in a single compilation unit Is 32767 when run 
time error checking Is selected. 

o Nesting level of structured statements Is limited to 63 levels deep. 

o FOR statements can only be nested 15 levels deep. 

o Procedures may only be nested 50 levels deep. 

o Number of parameters passed to an xrefed procedure Is 127* while an 
xrefed function is limited to 126. 



o 



The reach of jump instructions is limited to 2**16 so the size of a 
module should be appropriately controlled. 



O o The stack frame size Is limited to 2**15 bytes. g^ ' 

££_Li!iIIAIIQ M .S 

o In general the size of arrays and strings should be limited to less than 
2**15 bytes. 

o Maximum number of procedures in a single module is limited to 254. 
o The maximum nesting level of procedures is 30. 

o The use of long Integer subranges Is not allowed in the following areas* 

o Array subscripts* .*..i«. 

o As the <flrst char> or as the <substrlng length> on any string 

reference* 
o As the selector on a case statement* 
o As a actual parameter to a formal reference parameter of type 

integer. , _ _„. 

o As the control variable, starting value or ending value of a FOR 

statement. 

o' The result of a Strlngrep operation on a floating point number is 
limited to 6 digits. 

© T 
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o Array site -1 1*1 ted to 2**32. 
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This section Is intended to provide sufficient detail to be able to 
understand those features where the compiler implementation lags the 
language specification. 

GiaEEAL 

CXEILIittliafiuiailan-r-QixiaUans 

o iSEQ function. 

o Restricting pointers to not point to data with less scope* 

o Initialization of static pointers to NIL and zeroing the adaptable 

descriptor fields is not done, 
o fSIZE of adaptable types* 

o Run tine checking on accessing fields of variant records not supported* 
o iCurrent.stack.frame intrinsic* 
o Support adaptable arrays of zero dimension* 
o Double Precision Floating Point (LONGREAL). 
o RESET TO with a relative pointer* 
o STRLENGTH of constant of constant Identifier* 

Library pragmat. fr^'j 

Pre-defined Identifiers are Implemented as reserved words. 
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CCCEXIAIIQti* 

o Relative Pointer Types* 

o General Intrinslcs* 

o Partial condition evaluation on OR operator not supported* 

o Actual value parameters > 1 word must be addressable* 

ani-nEmuaai 
ccaEmiiaus 

o Large value parameters are never copied* 

o If a non-local exit from a function is done* the function result value 

is always undefined* 
o Single Precision Floating Point (READ* 

LE-QEYlAIIfltti 

o Static Initialization. 

o PUSH statement is not supported* < 

o Relative Pointers* % 
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o General Intrinsic*. 

o Copies of adaptable value parameters are never aade* 

o C200 Intrlnslcs. 
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